Create Customer Offer [V3]

This API is used to create an individual offer (Regular Plan) or a Pool Plan for one of the customer children (sub-customers).

Version 3 of this API includes these additional features:

  • New Rate offer (plan) type with new capabilities, such as selective rates per offer (instead of cross-account offer)

  • The ability to link an existing offer or offers to a newly created offer

  • Plan Cost (charge for using the plan) availability to Rate-type offers

  • Renewal-date comprehensive information

  • Expiration-date comprehensive information

HTTP URL

 
POST /api/v3/customer/{id}/offer

Eligibility

The Requester is eligible to create new individual offers or Pool Plans for his sub-customers use.

The Requester is not eligible to create new individual offers or new Pool Plans for its own profile use.

API Request

Request Structure

Parameter

Type

M/O/CM

Description

name

String

M

Individual offer or Pool Plan offer name

Must be unique.

description

String

O

Offer description

type

String

M

Offer type.

ENUM valid values: USAGE, RATE, MONEY, POOL

cost

Decimal

M

Cost of the offer. May contain a decimal value.

If no cost is applied, send 0 (zero).

currency

String

M

Cost currency, such as USD, GBP, EUR.

renewalInterval

String

M

Renewal period interval.

ENUM valid values: DAILY, WEEKLY, MONTHLY, QUARTERLY, SEMI_ANNUALLY, ANNUALLY, ONE_TIME

renewalIntervalMethod

String

O

Determines how to set the renewal day.

  • ENUM valid values:
  • FIRST_DAY: Renewal day will be the first day of the renewal interval, for example, first of the month per MONTHLY interval.
  • SELF_DEFINED: Renewal day will be the day defined by the user, for example, 10th of the month per MONTHLY interval.
  • PLAN_ALLOCATION: Renewal day will be set based on the actual plan allocation (attachment) day.
    PLAN_ALLOCATION is not applicable to a Pool plan.
Default (not set) = FIRST_DAY

renewalIntervalDay

Numeric

CM

Determines the selected day of the selected period.

  • ENUM valid values:
  • DAILY: N/A
  • WEEKLY: 1–7
  • MONTHLY: 1–28
  • QUARTERLY: 1–90
  • SEMI_ANNUALLY: 1–180
  • ANNUALLY: 1–365
  • ONE_TIME: N/A
  • Mandatory only if the renewalIntervalMethod attribute has been set to SELF_DEFINED .

expirationType

String

O

Determines how to set the expiration date.

ENUM valid values:

FIXED: Fixed, predefined expiration date.

RELATIVE_ATTACHED: Time duration from the moment the plan was attached to the subscriber (SIM), for example, 10 days.
RELATIVE_ATTACHED is not applicable to a Pool plan.

RELATIVE_FIRST_USE: Time duration from the time the plan was first used by the subscriber, for example 10 days.
RELATIVE_FIRST_USE is not applicable to a Pool plan.

If not sent, the plan will not expire at all.

expirationDate

Date

CM

Determines the requested date as per the selected expiratioType.

Mandatory only if the expirationType parameter has been set to FIXED.

If populated for other expirationType settings or if not set, it is ignored.

expirationUnit

String

CM

Determines the time unit that should be used for expiration calculation.

ENUM valid values: DAY, WEEK, MONTH, YEAR

Mandatory only if the expirationType parameter differs from FIXED.

If populated for the FIXED expirationType parameter or if expirationType not set, it is ignored.

expirationValue

Numeric

CM

Determines the requested time value as per the selected expirationUnit.

Mandatory only if the expirationType parameter differs from FIXED.

If populated for the FIXED expirationType parameter or if expirationType not set, it is ignored.

isProrated

Boolean

O

Determines whether proration is calculated when the plan is attached to a subscriber.

Pool plan is not supported, so turning this flag on for a Pool Plan is ignored.

Rate plan is supported, but has no business meaning.

Range:

True = Proration is calculated when a plan is attached to a subscriber.

False = This plan is not prorated (upon plan attachment).

Default = False
isIncludingAccessFee

Boolean

O

Determine if the offer price already includes inherent access fee and surcharge fee.

  • True – Offer price includes access\surcharge fees. Once a calendar month, when registering on the network, the system will not charge additionally on top of the offer price.

  • False – Offer price does not include access\surcharge fee. Once a calendar month, when registering on the network, the system will charge the access\surcharge fees in addition to the offer price.

Default – False

money

Object

CM

Money type information object.

  • Mandatory when MONEY offer type was selected.

  • Ignored if a RATE, USAGE or POOL offer type was selected.

rate

Object

CM

Rate type definition object.

  • Mandatory when RATE offer type was selected.

  • Ignored if a USAGE, MONEY or POOL offer type was selected.

usage

Object

CM

Usage type information object.

  • Mandatory when a USAGE offer type was selected.

  • Ignored if a RATE, MONEY or POOL offer type was selected.

pool

Object

CM

Pool plan type information object.

  • Mandatory when the POOL offer type was selected.

  • Ignored if a USAGE, RATE or MONEY offer type was selected.

eligibleSubAccountIds

String

CM

Array of sub account UUIDs. Specified sub-account(s) are the accounts that are eligible to view and manage (attach/detach) this plan as part of the self-service feature.

If sent empty then none of the customer’s sub-accounts are eligible for this offer.

If the ALL keyword (ENUM) then all of the customer’s sub-accounts are eligible for this offer.

availabilityZone

UUID

O

Array of availability zone IDs that are assigned to this plan.

Empty array means that the plan is available in any zone.

linkedOffers

Object

O

Array of offer(s) object that should be linked to this offer. The order of the instances in the array determines their priority for charging.

An Empty array means that the created offer will not have any linked offers.

Money data objects

Element

Type

M/O/CM

Description

activationType

String

M

Defines plan activation behavior.

ENUM: REGULAR, FIRST_EVENT_PERIODIC, FIRST_EVENT_NON_PERIODIC

Rate data objects

Element

Type

M/O/CM

Description

type

String

O

Rate offer type. A Rate plan can be of these types: Account or Plan: Fixed.

The Account rate-plan type defines a rate plan for all sub-accounts.

A Plan:Fixed rate-plan type can tailor a fixed-rate plan for a specific sub account.

ENUM valid values: ACCOUNT, PLAN_FIXED

Default( if not sent): ACCOUNT
activationType

String

O

Define plan activation behavior. ENUM: REGULAR, FIRST_EVENT_PERIODIC, FIRST_EVENT_NON_PERIODIC.

NOTE: If not provided, will be taken from the plan template.

dataLimit

Decimal

O

Defines the maximum allowed DATA usage consumption.

dataLimitUnitType

String

CM

Data limit unit type.

ENUM valid values: KB, MB, GB

Mandatory when setting limit for data usage (‘dataLimit’).

Ignored if the ‘dataLimit’ element is empty.

smsLimit

Decimal

O

Define the maximum allowed SMS usage consumption. Unit counting is always a ‘unit’ for SMS type.

price

Object

CM

Array of plan price object.

Mandatory if the type is set to PLAN_FIXED. Ignored for the ACCOUNT type even if the value is filled in.

Price data objects

Element

Type

M/O/CM

Description

type

String

M

Usage type

ENUM valid values: DATA, SMS

unitType

String

CM

Usage unit type = DATA.

ENUM valid values: KB, MB, GB

Mandatory for the DATA usage type.

Empty for the SMS usage type.

Ignored if populated for the SMS Usage type.

price

Decimal

M

Price per unit consumption.

Data: Price per KB/MB/GB

SMS: Price per SMS

currency

String

M

Price currency, such a USD, GBP, EUR

Usage data objects

Element

Type

M/O/CM

Description

activationType

String

M

Defines plan activation behavior.

ENUM: REGULAR, FIRST_EVENT_PERIODIC, FIRST_EVENT_NON_PERIODIC

usageType

Object

M

Array of usage types object.

Usage Type data objects

Element

Type

M/O/CM

Description

type

String

M

Type of the usage.

ENUM valid values: DATA, SMS

value

Decimal

M

Allowance value.

Data consumption for DATA type.

Unit counting for SMS type.

unitType

String

CM

Usage unit type. DATA

ENUM valid values: KB, MB, GB

Mandatory for DATA usage type. Empty for SMS usage type.

Ignored if populated for SMS usage type.

Pool data objects

Element

Type

M/O/CM

Description

type

String

M

Pool plan type. ENUM valid values: FIXED, ACCUMULATIVE

activationType

String

M

Defines pool plan activation behavior.

ENUM: REGULAR, FIRST_EVENT_PERIODIC, FIRST_EVENT_NON_PERIODIC

poolusageType

Object

M

Array of (pool) usage types object.

Pool Usage Type data objects

Element

Type

M/O/CM

Description

type

String

M

Type of the usage.

ENUM valid values: DATA, SMS

value

Decimal

M

Allowance value.

Data consumption for DATA type.

Unit counting for SMS type.

unitType

String

CM

Usage unit type = DATA

ENUM valid values: KB, MB, GB

Mandatory for DATA usage type. Empty for SMS usage type.

Ignored if populated for SMS usage type.

limitValue

Decimal

O

Defines usage limit value.

Data consumption for DATA type.

Unit counting for SMS type.

limitUnitType

String

CM

Limit unit type = DATA

ENUM valid values: KB, MB, GB

Mandatory when setting the limit for DATA usage. Empty for SMS usage type.

Ignored if populated for SMS usage type.

Linked Offers data objects

Element

Type

M/O/CM

Description

id

UUID

M

Universal unique ID of the offer to link to this offer.

isPinned

Boolean

O

[Future Feature]

Determines whether or not the linked offer can be removed from this newly created offer in the future.

True = Linked offer is fixed and cannot be removed.

False = Linked offer is not fixed and can be removed

Default = True (if not sent)

Future Feature so ignored if sent until implemented.

unitType

String

CM

Usage unit type = DATA

ENUM valid values: KB, MB, GB

Mandatory for DATA usage type. Empty for SMS usage type.

Ignored if populated for SMS usage type.

limitValue

Decimal

O

Defines usage limit value.

Data consumption for DATA type.

Unit counting for SMS type.

limitUnitType

String

CM

Limit unit type = DATA

ENUM valid values: KB, MB, GB

Mandatory when setting the limit for DATA usage. Empty for SMS usage type.

Ignored if populated for SMS usage type.

API Response

Response Structure

Element

Type

M/O/CM

Description

errorCode

String

O

Failure code.

errorMessage

String

O

Failure message.

content

Object

O

Array of main response body object displayed when an API call was successful. For a failure, it will be empty.

pageable

Object

O

Paging information object displayed when an API call was successful. For a failure, it will be empty.

Content data objects

Element

Type

M/O/CM

Description

offerId

UUID

M

The UUID generated by a new offer

requestId

UUID

M

Request instance ID.

To be used by external systems to query the call (operation) status:

In progress

Successful

Failed.

Pageable data objects

Element

Type

M/O/CM

Description

page

Numeric

M

Page number

size

Numeric

M

Page size. Number of requested elements per page

totalPages

Numeric

M

Total amount of available pages per requested page size

totalElements

Numeric

M

Total amount of retrieved elements

Error Codes

In addition to the general success and failure codes, the following error codes are possible.

Code

Message

GLOBAL_1001

Service unavailable. Please try again

Examples

Request Body: Regular Plan

Copy 
{  
  "name": "Basic roaming bundle",
  "description": "Basic roaming bundle description",
  "type": "USAGE",
  "cost": 20.5,
  "currency": "USD",
  "renewalInterval": "MONTHLY",
  "renewalIntervalMethod": "FIRST_DAY",
  "renewalIntervalDay": "",
  "expirationType": "FIXED",
  "expirationDate": "09092023",
  "expirationUnit": "",
  "expirationValue": "",
  "isProrated": true,
  "isIncludingAccessFee": false,
  "usage": {
    "activationType": "REGULAR",
    "usageType": [
      {
        "type": "DATA",
        "value": 50,
        "unitType": "MB"
      },
      {
        "type": "SMS",
        "value": 100,
        "unitType": ""
      }
    ]
  },
  "eligibleSubAccountIds": [
    "ee74dca6-8e7f-4b85-a42b-13860913b3b1",
    "ff74aca1-8d1f-4b85-a62a-93360913b370"
  ],
  "availabilityZone": [
    "ab74dca1-8d7f-4b85-a42b-13822913c3b3"
  ],
  "linkedOffers": [
    {
      "id": "ff74dca6-8e7f-4b85-a42b-13860913b370",
      "isPinned": true
    },
    {
      "id": "ff74dba6-8e7f-4b15-a42b-13810913b371",
      "isPinned": true
    }
  ]
}

Request Body: Pool Plan

Copy 
{  
  "name": "Accumulative Basic Pool Plan",
  "description": "Basic roaming bundle description",
  "type": "POOL",
  "cost": 20.5,
  "currency": "USD",
  "renewalInterval": "MONTHLY",
  "renewalIntervalMethod": "FIRST_DAY",
  "renewalIntervalDay": "",
  "expirationType": "FIXED",
  "expirationDate": "09092023",
  "expirationUnit": "",
  "expirationValue": "",
  "isProrated": true,
  "isIncludingAccessFee": false,
  "pool": {
    "type": "ACCUMULATIVE",
    "activationType": "REGULAR",
    "poolUsageType": [
      {
        "type": "DATA",
        "value": 50,
        "unitType": "MB",
        "limitValue": 20,
        "limitUnitType": "MB"
      },
      {
        "type": "SMS",
        "value": 100,
        "unitType": "",
        "limitValue": 10,
        "limitUnitType": ""
      }
    ]
  },
  "eligibleSubAccountIds": [
    "ee74dca6-8e7f-4b85-a42b-13860913b3b1"
  ],
  "availabilityZone": [
    "ab74dca1-8d7f-4b85-a42b-13822913c3b3"
  ],
  "linkedOffers": [
    {
      "id": "ff74dca6-8e7f-4b85-a42b-13860913b370",
      "isPinned": true
    },
    {
      "id": "ff74dba6-8e7f-4b15-a42b-13810913b371",
      "isPinned": true
    }
  ]
}

Response Body: Success ACK

Copy 
{
  "errorCode": "",
  "errorMessage": "",
  "content": [
    {
      "requestId": "ff74dca6-8e7f-4b85-a42b-13860913b370",
      "offerId": "ee74dcd7-8e7f-4c45-a42b-13860913b129"
    }
  ],
  "pageable": {
    "page": 0,
    "size": 10,
    "totalPages": 1,
    "totalElements": 1
  }
}

Response Body: Failure NAK

Copy 
{
  "errorCode": "GLOBAL_1001",
  "errorMessage": "Service unavailable. Please try again",
  "content": "",
  "pageable": ""
}